<HTML>
<TITLE>module shallow_physics</TITLE>
<BODY BGCOLOR="#ffefd5" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=-2>
<A HREF="#PUBLIC INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#PUBLIC ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#DIAGNOSTIC FIELDS">DIAGNOSTICS</A> /
<A HREF="#ERROR MESSAGES">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>Module shallow_physics_mod</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Isaac Held, Bruce Wyman
     <B>Reviewers:</B>
     <B>Change history:</B> <A HREF="http://www.gfdl.noaa.gov/fms-cgi-bin/cvsweb.cgi/FMS
/atmos/param/shallow_physics/shallow_physics.f90">WebCVS Log for shallow_physics.f90</A>

</PRE>
</A><!-- END HEADER -->
</PRE>
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

    Provides simple forcing for a shallow water model.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>

    Forcing is generated by relaxing geopotential height to an
    equilibrium state. The velocities are also relaxed linearly
    to zero.

    Two mass sources may be specified. The ITCZ source results in a 
    zonally symmetric Hadley cell response. The monsoonal source
    results in a subtropical anticyclone. When both the ITCZ and
    monsoonal sources are present (the default), one also generates a
    quasi-stationary Rossby wave emanating from the monsoonal source.

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="OTHER MODULES USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN OTHER MODULES USED -->
<PRE>

           fms_mod
  time_manager_mod

</PRE>
</A><!-- END OTHER MODULES USED -->
<!--------------------------------------------------------------------->
<A NAME="PUBLIC INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN PUBLIC INTERFACE -->
<PRE>

  use shallow_physics_mod [,only: shallow_physics_init,
                             shallow_physics,
                             shallow_physics_end     ]

shallow_physics_init           : initializes module
shallow_physics                : adds tendencies to existing tendencies
shallow_physics_end            : releases memory and terminates the module

<b>Notes:</b>

 Optional namelist input can be read from file input.nml.
 No restart files are needed or generated by this module.
 No data files are needed.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="PUBLIC ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN PUBLIC ROUTINES -->
<PRE>

<b>call shallow_physics_init</b> ( axes, Time, lon, lat )

 INPUT:

    axes -- integer, dimension(4)
        axis indices (x,y,zfull,zhalf) returned by module diag_manager_mod

    Time -- type(time_type)
        the current time

    lon  -- longitude in radians at the center of a grid box
              [real, dimension(:) or dimension(:,:)]

    lat  -- latitude in radians at the center of a grid box
              [real, dimension(:) or dimension(:,:)]

<HR>

<b>call shallow_physics</b> ( is, ie, js, je, timelev, dt, Time,
                  um, vm, hm, u, v, h, u_dt, v_dt, h_dt )
    
 INPUT:  is, ie, js, je, timelev, dt, Time, u, v, h, um, vm, hm

    is, ie, js, je -- integer, scalar
        indices of the data window being passed

    timelev -- integer, scalar
        time level used to compute the forcing
        if timelev = -1, values at previous time level (tau-1) are used (um,vm,hm)
        if timelev =  0, values at current time level (tau) are used (u,v,h)
        if timelev = +1, values at next time level (tau+1) are used (e.g., um+dt*u_dt)

    dt -- real, scalar
        the time step (seconds)
        for leap-frog schemes use 2*dt

    Time -- type(time_type)
        the current time

    um, vm, hm -- real, dimension(:.:)
        zonal wind (m/s), meridional wind(m/s), geopotential height (m2/s2) 
        at the previous time level

    u, v, h -- real, dimension(:.:)
        zonal wind (m/s), meridional wind(m/s), geopotential height (m2/s2) 
        at the current time level

 IN/OUT:

    u_dt, v_dt, h_dt -- real, dimension(:,:)
       u_dt = du/dt = tendency of u (m/(s^2)), etc
       output has heating and friction added to input tendencies 

</PRE>
</A><!-- END PUBLIC ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

(all values listed are default values)   

logical :: no_forcing = .false.  Turns off all forcing.
                                 (Interfaces become dummy routines)

real    :: h_0             = 3.e04 (m2/s2)   mean height of flow
real    :: h_monsoon       = 2.e04 (m2/s2)   amplitude of monsoon source
real    :: lon_monsoon     =  90.0 (degrees) longitude of monsoon source origin
real    :: lat_monsoon     =  25.0 (degrees) latitude of monsoon source origin
real    :: width_monsoon   =  15.0 (degrees) width of monsoon source
real    :: h_itcz          = 1.e05 (m2/s2)   amplitude of ITCZ source
real    :: width_itcz      =  4.0  (degrees) latitude width of ITCZ source

real    :: fric_damp_time  = -20.0  frictional damping time
real    :: therm_damp_time = -10.0  thermal damping time

damping times units are (1/s) 
  The namelist value is the inverse of damping time,
  if positive the units are in (seconds), and
  if negative the units are in (days).

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DIAGNOSTIC FIELDS">
<HR>
<H4>DIAGNOSTIC FIELDS</H4>
<PRE>

None.

</PRE>
</A><!-- END DIAGNOSTIC FIELDS -->
<!--------------------------------------------------------------------->
<A NAME="ERROR MESSAGES">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERROR MESSAGES -->
<PRE>

<b>FATAL errors in shallow_physics_mod</b>

    <b>module has already been initialized</b>
        You have attempted to call shallow_physics_init more than once.
        If this is what you intend to do, then call shallow_physics_end
        before recalling shallow_physics_init.

    <b>module has not been initialized</b>
        A FATAL error will occur in shallow_physics if you 
        have not previously called shallow_physics_init.
        Also, a WARNING will occur in shallow_physics_end if you
        have not previously called shallow_physics_init.

    <b>invalid value for timelev argument</b>
        The value of timelev must be set as -1, 0, or +1.
        Refer to the namelist documentation for details.

</PRE>
</A><!-- END ERROR MESSAGES -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

None.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

None.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="FUTURE PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN FUTURE PLANS -->
<PRE>

None.

</PRE>
</A><!-- END FUTURE PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
